{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introduction to the Spatially Enabled DataFrame\n",
    "\n",
    "The [`Spatially Enabled DataFrame`](/python/api-reference/arcgis.features.toc.html#geoaccessor) (SEDF) creates a simple, intutive object that can easily manipulate geometric and attribute data.\n",
    "\n",
    "> _Note:_ The Spatially Enabled DataFrame is implemented as the [GeoAccessor](/python/api-reference/arcgis.features.toc.html#geoaccessor) class in the API and is based upon the [Pandas DataFrame](http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe) object. The SEDF provides you excellent memory management, ability to handle larger datasets and is coded with the recommended Pandas pattern.\n",
    "\n",
    "The Spatially Enabled DataFrame inserts a custom namespace called `spatial` into the popular [Pandas](https://pandas.pydata.org/) [DataFrame](http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe) structure to give it spatial abilities. This allows you to use intutive, pandorable operations on both the attribute and spatial columns. Thus, the SEDF is based on data structures inherently suited to data analysis, with natural operations for the filtering and inspecting of subsets of values which are fundamental to statistical and geographic manipulations.\n",
    "\n",
    "The dataframe reads from many **sources**, including shapefiles, [Pandas](https://pandas.pydata.org/) [DataFrames](http://pandas.pydata.org/pandas-docs/stable/dsintro.html#dataframe), feature classes, GeoJSON, and Feature Layers.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This document outlines some fundamentals of using the `Spatially Enabled DataFrame` object for working with GIS data.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "toc": true
   },
   "source": [
    "<h1>Table of Contents<span class=\"tocSkip\"></span></h1>\n",
    "<div class=\"toc\"><ul class=\"toc-item\"><li><span><a href=\"#Introduction-to-the-Spatially-Enabled-DataFrame\" data-toc-modified-id=\"Introduction-to-the-Spatially-Enabled-DataFrame-1\"><span class=\"toc-item-num\">1&nbsp;&nbsp;</span>Introduction to the Spatially Enabled DataFrame</a></span><ul class=\"toc-item\"><li><span><a href=\"#Accessing-GIS-data\" data-toc-modified-id=\"Accessing-GIS-data-1.1\"><span class=\"toc-item-num\">1.1&nbsp;&nbsp;</span>Accessing GIS data</a></span><ul class=\"toc-item\"><li><span><a href=\"#Reading-Web-Layers\" data-toc-modified-id=\"Reading-Web-Layers-1.1.1\"><span class=\"toc-item-num\">1.1.1&nbsp;&nbsp;</span>Reading Web Layers</a></span></li><li><span><a href=\"#Reading-Feature-Layer-Data\" data-toc-modified-id=\"Reading-Feature-Layer-Data-1.1.2\"><span class=\"toc-item-num\">1.1.2&nbsp;&nbsp;</span>Reading Feature Layer Data</a></span><ul class=\"toc-item\"><li><span><a href=\"#Example:-Examining-Feature-Layer-content\" data-toc-modified-id=\"Example:-Examining-Feature-Layer-content-1.1.2.1\"><span class=\"toc-item-num\">1.1.2.1&nbsp;&nbsp;</span>Example: Examining Feature Layer content</a></span></li><li><span><a href=\"#Example:-Feature-Layer-Query-Results-to-a-Spatially-Enabled-DataFrame\" data-toc-modified-id=\"Example:-Feature-Layer-Query-Results-to-a-Spatially-Enabled-DataFrame-1.1.2.2\"><span class=\"toc-item-num\">1.1.2.2&nbsp;&nbsp;</span>Example: Feature Layer Query Results to a Spatially Enabled DataFrame</a></span></li></ul></li></ul></li><li><span><a href=\"#Accessing-local-GIS-data\" data-toc-modified-id=\"Accessing-local-GIS-data-1.2\"><span class=\"toc-item-num\">1.2&nbsp;&nbsp;</span>Accessing local GIS data</a></span><ul class=\"toc-item\"><li><span><a href=\"#Example:-Reading-a-Shapefile\" data-toc-modified-id=\"Example:-Reading-a-Shapefile-1.2.1\"><span class=\"toc-item-num\">1.2.1&nbsp;&nbsp;</span>Example: Reading a Shapefile</a></span></li><li><span><a href=\"#Example:-Reading-a-Featureclass-from-FileGDB\" data-toc-modified-id=\"Example:-Reading-a-Featureclass-from-FileGDB-1.2.2\"><span class=\"toc-item-num\">1.2.2&nbsp;&nbsp;</span>Example: Reading a Featureclass from FileGDB</a></span></li></ul></li><li><span><a href=\"#Saving-Spatially-Enabled-DataFrames\" data-toc-modified-id=\"Saving-Spatially-Enabled-DataFrames-1.3\"><span class=\"toc-item-num\">1.3&nbsp;&nbsp;</span>Saving Spatially Enabled DataFrames</a></span><ul class=\"toc-item\"><li><span><a href=\"#Export-Options\" data-toc-modified-id=\"Export-Options-1.3.1\"><span class=\"toc-item-num\">1.3.1&nbsp;&nbsp;</span>Export Options</a></span></li><li><span><a href=\"#Export-to-Feature-Class\" data-toc-modified-id=\"Export-to-Feature-Class-1.3.2\"><span class=\"toc-item-num\">1.3.2&nbsp;&nbsp;</span>Export to Feature Class</a></span><ul class=\"toc-item\"><li><span><a href=\"#Example:-Export-a-whole-dataset-to-a-shapefile:\" data-toc-modified-id=\"Example:-Export-a-whole-dataset-to-a-shapefile:-1.3.2.1\"><span class=\"toc-item-num\">1.3.2.1&nbsp;&nbsp;</span>Example: Export a whole dataset to a shapefile:</a></span></li><li><span><a href=\"#Example:-Export-dataset-with-a-subset-of-columns-and-top-5-records-to-a-shapefile:\" data-toc-modified-id=\"Example:-Export-dataset-with-a-subset-of-columns-and-top-5-records-to-a-shapefile:-1.3.2.2\"><span class=\"toc-item-num\">1.3.2.2&nbsp;&nbsp;</span>Example: Export dataset with a subset of columns and top 5 records to a shapefile:</a></span></li><li><span><a href=\"#Example:-Export-dataset-to-a-featureclass-in-FileGDB:\" data-toc-modified-id=\"Example:-Export-dataset-to-a-featureclass-in-FileGDB:-1.3.2.3\"><span class=\"toc-item-num\">1.3.2.3&nbsp;&nbsp;</span>Example: Export dataset to a featureclass in FileGDB:</a></span></li></ul></li><li><span><a href=\"#Publish-as-a-Feature-Layer\" data-toc-modified-id=\"Publish-as-a-Feature-Layer-1.3.3\"><span class=\"toc-item-num\">1.3.3&nbsp;&nbsp;</span>Publish as a Feature Layer</a></span><ul class=\"toc-item\"><li><span><a href=\"#Example:-Publishing-as-a-feature-layer:\" data-toc-modified-id=\"Example:-Publishing-as-a-feature-layer:-1.3.3.1\"><span class=\"toc-item-num\">1.3.3.1&nbsp;&nbsp;</span>Example: Publishing as a feature layer:</a></span></li></ul></li></ul></li></ul></li></ul></div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "from arcgis.features import GeoAccessor, GeoSeriesAccessor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing GIS data\n",
    "\n",
    "GIS users need to work with both published layers on remote servers (web layers) and local data, but the ability to manipulate these datasets without permanently copying the data is lacking. The `Spatial Enabled DataFrame` solves this problem because it is an in-memory object that can read, write and manipulate geospatial data.\n",
    "\n",
    "The SEDF integrates with Esri's [`ArcPy` site-package](http://pro.arcgis.com/en/pro-app/arcpy/get-started/what-is-arcpy-.htm) as well as the open source [`pyshp`](https://github.com/GeospatialPython/pyshp/), [`shapely`](https://github.com/Toblerity/Shapely) and [`fiona`](https://github.com/Toblerity/Fiona) packages. This means the ArcGIS API for Python SEDF can use either of these geometry engines to provide you options for easily working with geospatial data regardless of your platform. The SEDF transforms data into the formats you desire so you can use Python functionality to analyze and visualize geographic information.\n",
    "\n",
    "Data can be read and scripted to automate workflows and just as easily visualized on maps in [`Jupyter Lab notebooks`](../using-the-jupyter-notebook-environment/). The SEDF can export data as feature classes or publish them directly to servers for sharing according to your needs. \n",
    "\n",
    "> **_Note:_** When leveraging Esri hosted content, organizations should review the [ArcGIS Online terms of use](https://doc.arcgis.com/en/arcgis-online/reference/terms-of-use.htm), as well as the terms of use for the data layer to ensure they are in compliance with extracting data and/or making it available in other systems.\n",
    "\n",
    "Let's explore some of the different options available with the versatile `Spatial Enabled DataFrame` namespaces:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Reading Web Layers\n",
    "\n",
    "[`Feature layers`](https://doc.arcgis.com/en/arcgis-online/share-maps/hosted-web-layers.htm) hosted on [**ArcGIS Online**](https://www.arcgis.com) or [**ArcGIS Enterprise**](http://enterprise.arcgis.com/en/) can be easily read into a Spatially Enabled DataFrame using the [`from_layer`](/python/api-reference/arcgis.features.toc.html?highlight=from_layer#arcgis.features.GeoAccessor.from_layer) method. Once you read it into a SEDF object, you can create reports, manipulate the data, or convert it to a form that is comfortable and makes sense for its intended purpose.\n",
    "\n",
    "**Example: Retrieving an ArcGIS Online [`item`](https://developers.arcgis.com/rest/users-groups-and-items/publish-item.htm) and using the [`layers`](/python/api-reference/arcgis.gis.toc.html#layer) property to inspect the first 5 records of the layer**\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>AGE_10_14</th>\n",
       "      <th>AGE_15_19</th>\n",
       "      <th>AGE_20_24</th>\n",
       "      <th>AGE_25_34</th>\n",
       "      <th>AGE_35_44</th>\n",
       "      <th>AGE_45_54</th>\n",
       "      <th>AGE_55_64</th>\n",
       "      <th>AGE_5_9</th>\n",
       "      <th>AGE_65_74</th>\n",
       "      <th>AGE_75_84</th>\n",
       "      <th>...</th>\n",
       "      <th>PLACEFIPS</th>\n",
       "      <th>POP2010</th>\n",
       "      <th>POPULATION</th>\n",
       "      <th>POP_CLASS</th>\n",
       "      <th>RENTER_OCC</th>\n",
       "      <th>SHAPE</th>\n",
       "      <th>ST</th>\n",
       "      <th>STFIPS</th>\n",
       "      <th>VACANT</th>\n",
       "      <th>WHITE</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2144</td>\n",
       "      <td>2314</td>\n",
       "      <td>2002</td>\n",
       "      <td>3531</td>\n",
       "      <td>3887</td>\n",
       "      <td>5643</td>\n",
       "      <td>6353</td>\n",
       "      <td>2067</td>\n",
       "      <td>5799</td>\n",
       "      <td>2850</td>\n",
       "      <td>...</td>\n",
       "      <td>0408220</td>\n",
       "      <td>39540</td>\n",
       "      <td>40346</td>\n",
       "      <td>6</td>\n",
       "      <td>6563</td>\n",
       "      <td>{\"x\": -12751215.004681978, \"y\": 4180278.406256...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>6703</td>\n",
       "      <td>32367</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>876</td>\n",
       "      <td>867</td>\n",
       "      <td>574</td>\n",
       "      <td>1247</td>\n",
       "      <td>1560</td>\n",
       "      <td>2122</td>\n",
       "      <td>2342</td>\n",
       "      <td>733</td>\n",
       "      <td>2157</td>\n",
       "      <td>975</td>\n",
       "      <td>...</td>\n",
       "      <td>0424895</td>\n",
       "      <td>14364</td>\n",
       "      <td>14847</td>\n",
       "      <td>6</td>\n",
       "      <td>1397</td>\n",
       "      <td>{\"x\": -12755627.731115643, \"y\": 4164465.572856...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>1389</td>\n",
       "      <td>12730</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>1000</td>\n",
       "      <td>1003</td>\n",
       "      <td>833</td>\n",
       "      <td>2311</td>\n",
       "      <td>2063</td>\n",
       "      <td>2374</td>\n",
       "      <td>3631</td>\n",
       "      <td>1068</td>\n",
       "      <td>6165</td>\n",
       "      <td>3776</td>\n",
       "      <td>...</td>\n",
       "      <td>0425030</td>\n",
       "      <td>26265</td>\n",
       "      <td>26977</td>\n",
       "      <td>6</td>\n",
       "      <td>1963</td>\n",
       "      <td>{\"x\": -12734674.294574209, \"y\": 3850472.723091...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>9636</td>\n",
       "      <td>22995</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>2730</td>\n",
       "      <td>2850</td>\n",
       "      <td>2194</td>\n",
       "      <td>4674</td>\n",
       "      <td>5240</td>\n",
       "      <td>7438</td>\n",
       "      <td>8440</td>\n",
       "      <td>2499</td>\n",
       "      <td>8145</td>\n",
       "      <td>4608</td>\n",
       "      <td>...</td>\n",
       "      <td>0439370</td>\n",
       "      <td>52527</td>\n",
       "      <td>55041</td>\n",
       "      <td>7</td>\n",
       "      <td>6765</td>\n",
       "      <td>{\"x\": -12725332.21151233, \"y\": 4096532.0908223...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>9159</td>\n",
       "      <td>47335</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>2732</td>\n",
       "      <td>2965</td>\n",
       "      <td>2024</td>\n",
       "      <td>3182</td>\n",
       "      <td>3512</td>\n",
       "      <td>3109</td>\n",
       "      <td>1632</td>\n",
       "      <td>2497</td>\n",
       "      <td>916</td>\n",
       "      <td>467</td>\n",
       "      <td>...</td>\n",
       "      <td>0463470</td>\n",
       "      <td>25505</td>\n",
       "      <td>29767</td>\n",
       "      <td>6</td>\n",
       "      <td>1681</td>\n",
       "      <td>{\"x\": -12770984.257542243, \"y\": 3826624.133935...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>572</td>\n",
       "      <td>16120</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 51 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "   AGE_10_14  AGE_15_19  AGE_20_24  AGE_25_34  AGE_35_44  AGE_45_54  \\\n",
       "0       2144       2314       2002       3531       3887       5643   \n",
       "1        876        867        574       1247       1560       2122   \n",
       "2       1000       1003        833       2311       2063       2374   \n",
       "3       2730       2850       2194       4674       5240       7438   \n",
       "4       2732       2965       2024       3182       3512       3109   \n",
       "\n",
       "   AGE_55_64  AGE_5_9  AGE_65_74  AGE_75_84  ...    PLACEFIPS  POP2010  \\\n",
       "0       6353     2067       5799       2850  ...      0408220    39540   \n",
       "1       2342      733       2157        975  ...      0424895    14364   \n",
       "2       3631     1068       6165       3776  ...      0425030    26265   \n",
       "3       8440     2499       8145       4608  ...      0439370    52527   \n",
       "4       1632     2497        916        467  ...      0463470    25505   \n",
       "\n",
       "   POPULATION  POP_CLASS  RENTER_OCC  \\\n",
       "0       40346          6        6563   \n",
       "1       14847          6        1397   \n",
       "2       26977          6        1963   \n",
       "3       55041          7        6765   \n",
       "4       29767          6        1681   \n",
       "\n",
       "                                               SHAPE  ST STFIPS VACANT  WHITE  \n",
       "0  {\"x\": -12751215.004681978, \"y\": 4180278.406256...  AZ     04   6703  32367  \n",
       "1  {\"x\": -12755627.731115643, \"y\": 4164465.572856...  AZ     04   1389  12730  \n",
       "2  {\"x\": -12734674.294574209, \"y\": 3850472.723091...  AZ     04   9636  22995  \n",
       "3  {\"x\": -12725332.21151233, \"y\": 4096532.0908223...  AZ     04   9159  47335  \n",
       "4  {\"x\": -12770984.257542243, \"y\": 3826624.133935...  AZ     04    572  16120  \n",
       "\n",
       "[5 rows x 51 columns]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from arcgis import GIS\n",
    "gis = GIS()\n",
    "item = gis.content.search(\n",
    "    \"USA Major Cities\", item_type=\"Feature layer\", outside_org=True)[0]\n",
    "flayer = item.layers[0]\n",
    "\n",
    "# create a Spatially Enabled DataFrame object\n",
    "sdf = pd.DataFrame.spatial.from_layer(flayer)\n",
    "sdf.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When you inspect the `type` of the object, you get back a standard pandas `DataFrame` object. However, this object now has an additional `SHAPE` column that allows you to perform geometric operations. In other words, this `DataFrame` is now geo-aware.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "pandas.core.frame.DataFrame"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "type(sdf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Further, the `DataFrame` has a new `spatial` property that provides a list of geoprocessing operations that can be performed on the object. The rest of the guides in this section go into details of how to use these functionalities. So, sit tight.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Reading Feature Layer Data\n",
    "\n",
    "As seen above, the SEDF can consume a `Feature Layer` served from either ArcGIS Online or ArcGIS Enterprise orgs. Let's take a step-by-step approach to break down the notebook cell above and then extract a subset of records from the feature layer.\n",
    "\n",
    "#### Example: Examining Feature Layer content\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Use the `from_layer` method on the SEDF to instantiate a data frame from an item's `layer` and inspect the first 5 records.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n",
       "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n",
       "                       <a href='https://deldev.maps.arcgis.com/home/item.html?id=85d0ca4ea1ca4b9abf0c51b9bd34de2e' target='_blank'>\n",
       "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n",
       "                       </a>\n",
       "                    </div>\n",
       "\n",
       "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n",
       "                        <a href='https://deldev.maps.arcgis.com/home/item.html?id=85d0ca4ea1ca4b9abf0c51b9bd34de2e' target='_blank'><b>USA Major Cities</b>\n",
       "                        </a>\n",
       "                        <br/>This layer presents the locations of cities within the United States with populations of approximately 10,000 or greater, all state capitals, and the national capital.<img src='https://deldev.maps.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/featureshosted16.png' style=\"vertical-align:middle;\">Feature Layer Collection by esri_dm\n",
       "                        <br/>Last Modified: August 22, 2019\n",
       "                        <br/>0 comments, 1,839,428 views\n",
       "                    </div>\n",
       "                </div>\n",
       "                "
      ],
      "text/plain": [
       "<Item title:\"USA Major Cities\" type:Feature Layer Collection owner:esri_dm>"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "known_item = gis.content.search(\n",
    "    \"USA Major Cities\", item_type=\"Feature layer\", outside_org=True)[0]\n",
    "\n",
    "known_item"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>AGE_10_14</th>\n",
       "      <th>AGE_15_19</th>\n",
       "      <th>AGE_20_24</th>\n",
       "      <th>AGE_25_34</th>\n",
       "      <th>AGE_35_44</th>\n",
       "      <th>AGE_45_54</th>\n",
       "      <th>AGE_55_64</th>\n",
       "      <th>AGE_5_9</th>\n",
       "      <th>AGE_65_74</th>\n",
       "      <th>AGE_75_84</th>\n",
       "      <th>...</th>\n",
       "      <th>PLACEFIPS</th>\n",
       "      <th>POP2010</th>\n",
       "      <th>POPULATION</th>\n",
       "      <th>POP_CLASS</th>\n",
       "      <th>RENTER_OCC</th>\n",
       "      <th>SHAPE</th>\n",
       "      <th>ST</th>\n",
       "      <th>STFIPS</th>\n",
       "      <th>VACANT</th>\n",
       "      <th>WHITE</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>2144</td>\n",
       "      <td>2314</td>\n",
       "      <td>2002</td>\n",
       "      <td>3531</td>\n",
       "      <td>3887</td>\n",
       "      <td>5643</td>\n",
       "      <td>6353</td>\n",
       "      <td>2067</td>\n",
       "      <td>5799</td>\n",
       "      <td>2850</td>\n",
       "      <td>...</td>\n",
       "      <td>0408220</td>\n",
       "      <td>39540</td>\n",
       "      <td>40346</td>\n",
       "      <td>6</td>\n",
       "      <td>6563</td>\n",
       "      <td>{\"x\": -12751215.004681978, \"y\": 4180278.406256...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>6703</td>\n",
       "      <td>32367</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>876</td>\n",
       "      <td>867</td>\n",
       "      <td>574</td>\n",
       "      <td>1247</td>\n",
       "      <td>1560</td>\n",
       "      <td>2122</td>\n",
       "      <td>2342</td>\n",
       "      <td>733</td>\n",
       "      <td>2157</td>\n",
       "      <td>975</td>\n",
       "      <td>...</td>\n",
       "      <td>0424895</td>\n",
       "      <td>14364</td>\n",
       "      <td>14847</td>\n",
       "      <td>6</td>\n",
       "      <td>1397</td>\n",
       "      <td>{\"x\": -12755627.731115643, \"y\": 4164465.572856...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>1389</td>\n",
       "      <td>12730</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>1000</td>\n",
       "      <td>1003</td>\n",
       "      <td>833</td>\n",
       "      <td>2311</td>\n",
       "      <td>2063</td>\n",
       "      <td>2374</td>\n",
       "      <td>3631</td>\n",
       "      <td>1068</td>\n",
       "      <td>6165</td>\n",
       "      <td>3776</td>\n",
       "      <td>...</td>\n",
       "      <td>0425030</td>\n",
       "      <td>26265</td>\n",
       "      <td>26977</td>\n",
       "      <td>6</td>\n",
       "      <td>1963</td>\n",
       "      <td>{\"x\": -12734674.294574209, \"y\": 3850472.723091...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>9636</td>\n",
       "      <td>22995</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>2730</td>\n",
       "      <td>2850</td>\n",
       "      <td>2194</td>\n",
       "      <td>4674</td>\n",
       "      <td>5240</td>\n",
       "      <td>7438</td>\n",
       "      <td>8440</td>\n",
       "      <td>2499</td>\n",
       "      <td>8145</td>\n",
       "      <td>4608</td>\n",
       "      <td>...</td>\n",
       "      <td>0439370</td>\n",
       "      <td>52527</td>\n",
       "      <td>55041</td>\n",
       "      <td>7</td>\n",
       "      <td>6765</td>\n",
       "      <td>{\"x\": -12725332.21151233, \"y\": 4096532.0908223...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>9159</td>\n",
       "      <td>47335</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>2732</td>\n",
       "      <td>2965</td>\n",
       "      <td>2024</td>\n",
       "      <td>3182</td>\n",
       "      <td>3512</td>\n",
       "      <td>3109</td>\n",
       "      <td>1632</td>\n",
       "      <td>2497</td>\n",
       "      <td>916</td>\n",
       "      <td>467</td>\n",
       "      <td>...</td>\n",
       "      <td>0463470</td>\n",
       "      <td>25505</td>\n",
       "      <td>29767</td>\n",
       "      <td>6</td>\n",
       "      <td>1681</td>\n",
       "      <td>{\"x\": -12770984.257542243, \"y\": 3826624.133935...</td>\n",
       "      <td>AZ</td>\n",
       "      <td>04</td>\n",
       "      <td>572</td>\n",
       "      <td>16120</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 51 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "   AGE_10_14  AGE_15_19  AGE_20_24  AGE_25_34  AGE_35_44  AGE_45_54  \\\n",
       "0       2144       2314       2002       3531       3887       5643   \n",
       "1        876        867        574       1247       1560       2122   \n",
       "2       1000       1003        833       2311       2063       2374   \n",
       "3       2730       2850       2194       4674       5240       7438   \n",
       "4       2732       2965       2024       3182       3512       3109   \n",
       "\n",
       "   AGE_55_64  AGE_5_9  AGE_65_74  AGE_75_84  ...    PLACEFIPS  POP2010  \\\n",
       "0       6353     2067       5799       2850  ...      0408220    39540   \n",
       "1       2342      733       2157        975  ...      0424895    14364   \n",
       "2       3631     1068       6165       3776  ...      0425030    26265   \n",
       "3       8440     2499       8145       4608  ...      0439370    52527   \n",
       "4       1632     2497        916        467  ...      0463470    25505   \n",
       "\n",
       "   POPULATION  POP_CLASS  RENTER_OCC  \\\n",
       "0       40346          6        6563   \n",
       "1       14847          6        1397   \n",
       "2       26977          6        1963   \n",
       "3       55041          7        6765   \n",
       "4       29767          6        1681   \n",
       "\n",
       "                                               SHAPE  ST STFIPS VACANT  WHITE  \n",
       "0  {\"x\": -12751215.004681978, \"y\": 4180278.406256...  AZ     04   6703  32367  \n",
       "1  {\"x\": -12755627.731115643, \"y\": 4164465.572856...  AZ     04   1389  12730  \n",
       "2  {\"x\": -12734674.294574209, \"y\": 3850472.723091...  AZ     04   9636  22995  \n",
       "3  {\"x\": -12725332.21151233, \"y\": 4096532.0908223...  AZ     04   9159  47335  \n",
       "4  {\"x\": -12770984.257542243, \"y\": 3826624.133935...  AZ     04    572  16120  \n",
       "\n",
       "[5 rows x 51 columns]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Obtain the first feature layer from the item\n",
    "fl = known_item.layers[0]\n",
    "\n",
    "# Use the `from_layer` static method in the 'spatial' namespace on the Pandas' DataFrame\n",
    "sdf = pd.DataFrame.spatial.from_layer(fl)\n",
    "\n",
    "# Return the first 5 records.\n",
    "sdf.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> NOTE: See Pandas DataFrame [`head() method documentation`](https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.head.html) for details.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use sql queries to return a subset of records by leveraging the ArcGIS API for Python's [`Feature Layer`](/python/api-reference/arcgis.features.toc.html#featurelayer) object itself. When you run a [`query()`](/python/api-reference/arcgis.features.toc.html#arcgis.features.FeatureLayer.query) on a `FeatureLayer`, you get back a `FeatureSet` object. Calling the `sdf` property of the `FeatureSet` returns a Spatially Enabled DataFrame object. We then use the data frame's [`head()`](http://pandas.pydata.org/pandas-docs/stable/generated/pandas.core.groupby.GroupBy.head.html#pandas.core.groupby.GroupBy.head) method to return the first 5 records and a subset of columns from the DataFrame:\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Example: Feature Layer Query Results to a Spatially Enabled DataFrame\n",
    "\n",
    "We'll use the `AGE_45_54` column to query the data frame and return a new `DataFrame` with a subset of records. We can use the built-in [`zip()`](https://docs.python.org/3/library/functions.html#zip) function to print the data frame attribute field names, and then use data frame syntax to view specific attribute fields in the output:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Filter feature layer records with a sql query.\n",
    "# See https://developers.arcgis.com/rest/services-reference/query-feature-service-layer-.htm\n",
    "\n",
    "df = fl.query(where=\"AGE_45_54 < 1500\").sdf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "AGE_10_14                     AGE_15_19                     AGE_20_24                     AGE_25_34\n",
      "AGE_35_44                     AGE_45_54                     AGE_55_64                     AGE_5_9\n",
      "AGE_65_74                     AGE_75_84                     AGE_85_UP                     AGE_UNDER5\n",
      "AMERI_ES                      ASIAN                         AVE_FAM_SZ                    AVE_HH_SZ\n",
      "BLACK                         CAPITAL                       CLASS                         FAMILIES\n",
      "FEMALES                       FHH_CHILD                     FID                           HAWN_PI\n",
      "HISPANIC                      HOUSEHOLDS                    HSEHLD_1_F                    HSEHLD_1_M\n",
      "HSE_UNITS                     MALES                         MARHH_CHD                     MARHH_NO_C\n",
      "MED_AGE                       MED_AGE_F                     MED_AGE_M                     MHH_CHILD\n",
      "MULT_RACE                     NAME                          OBJECTID                      OTHER\n",
      "OWNER_OCC                     PLACEFIPS                     POP2010                       POPULATION\n",
      "POP_CLASS                     RENTER_OCC                    SHAPE                         ST\n"
     ]
    }
   ],
   "source": [
    "for a, b, c, d in zip(df.columns[::4], df.columns[1::4], df.columns[2::4], df.columns[3::4]):\n",
    "    print(\"{:<30}{:<30}{:<30}{:<}\".format(a, b, c, d))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>NAME</th>\n",
       "      <th>AGE_45_54</th>\n",
       "      <th>POP2010</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Somerton</td>\n",
       "      <td>1411</td>\n",
       "      <td>14287</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Anderson</td>\n",
       "      <td>1333</td>\n",
       "      <td>9932</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Camp Pendleton South</td>\n",
       "      <td>127</td>\n",
       "      <td>10616</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Citrus</td>\n",
       "      <td>1443</td>\n",
       "      <td>10866</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Commerce</td>\n",
       "      <td>1478</td>\n",
       "      <td>12823</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                   NAME  AGE_45_54  POP2010\n",
       "0              Somerton       1411    14287\n",
       "1              Anderson       1333     9932\n",
       "2  Camp Pendleton South        127    10616\n",
       "3                Citrus       1443    10866\n",
       "4              Commerce       1478    12823"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Return a subset of columns on just the first 5 records\n",
    "df[['NAME', 'AGE_45_54', 'POP2010']].head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Accessing local GIS data\n",
    "\n",
    "The SEDF can also access local geospatial data. Depending upon what Python modules you have installed, you'll have access to a wide range of functionality:\n",
    "\n",
    "- If the **`ArcPy`** module is installed, meaning you have installed [`ArcGIS Pro`](http://pro.arcgis.com/en/pro-app/) and have installed the ArcGIS API for Python in that same environment, the `DataFrame` then has methods to read a subset of the ArcGIS Desktop [supported data types](https://pro.arcgis.com/en/pro-app/latest/help/data/introduction/data-types.htm), most notably:\n",
    "- [`feature classes`](https://pro.arcgis.com/en/pro-app/latest/help/data/feature-classes/feature-classes.htm)\n",
    "- [`shapefiles`](https://pro.arcgis.com/en/pro-app/latest/help/data/shapefiles/working-with-shapefiles-in-arcgis-pro.htm),\n",
    "- [`Web layers`](https://pro.arcgis.com/en/pro-app/latest/help/data/services/use-map-image-layers.htm) and [`ArcGIS Online Hosted Feature Layers`](https://doc.arcgis.com/en/arcgis-online/share-maps/publish-features.htm)\n",
    "- [`OGC Service layers`](https://pro.arcgis.com/en/pro-app/latest/help/data/services/ogc-services.htm)\n",
    "- If the **`ArcPy`** module is not installed, the SEDF [`from_featureclass`](/python/api-reference/arcgis.features.toc.html#arcgis.features.GeoAccessor.from_featureclass) method only supports consuming an Esri `shapefile`.\n",
    "\n",
    "> _Note:_ You must install the `pyshp` package to read shapefiles in environments that don't have access to `ArcPy`.\n",
    "\n",
    "### Example: Reading a Shapefile\n",
    "\n",
    "> _Note:_ You must authenticate to `ArcGIS Online` or `ArcGIS Enterprise` to use the `from_featureclass()` method to read a shapefile with a Python interpreter that does not have access to `ArcPy`: <p><code>g2 = GIS(\"https://www.arcgis.com\", \"username\", \"password\")</code></p>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "g2 = GIS(profile=\"your_organization_profile\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>FID</th>\n",
       "      <th>NAME</th>\n",
       "      <th>CLASS</th>\n",
       "      <th>ST</th>\n",
       "      <th>STFIPS</th>\n",
       "      <th>PLACEFIP</th>\n",
       "      <th>CAPITAL</th>\n",
       "      <th>AREALAND</th>\n",
       "      <th>AREAWATER</th>\n",
       "      <th>POP_CLASS</th>\n",
       "      <th>...</th>\n",
       "      <th>MARHH_NO_C</th>\n",
       "      <th>MHH_CHILD</th>\n",
       "      <th>FHH_CHILD</th>\n",
       "      <th>FAMILIES</th>\n",
       "      <th>AVE_FAM_SZ</th>\n",
       "      <th>HSE_UNITS</th>\n",
       "      <th>VACANT</th>\n",
       "      <th>OWNER_OCC</th>\n",
       "      <th>RENTER_OCC</th>\n",
       "      <th>SHAPE</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <td>3552</td>\n",
       "      <td>3552</td>\n",
       "      <td>East Providence</td>\n",
       "      <td>City</td>\n",
       "      <td>RI</td>\n",
       "      <td>44</td>\n",
       "      <td>22960</td>\n",
       "      <td></td>\n",
       "      <td>13.405</td>\n",
       "      <td>3.208</td>\n",
       "      <td>6</td>\n",
       "      <td>...</td>\n",
       "      <td>5658</td>\n",
       "      <td>306</td>\n",
       "      <td>1414</td>\n",
       "      <td>12850</td>\n",
       "      <td>2.99</td>\n",
       "      <td>21309</td>\n",
       "      <td>779</td>\n",
       "      <td>12096</td>\n",
       "      <td>8434</td>\n",
       "      <td>{'x': -71.3608270663031, 'y': 41.8015001782688...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>3553</td>\n",
       "      <td>3553</td>\n",
       "      <td>Pawtucket</td>\n",
       "      <td>City</td>\n",
       "      <td>RI</td>\n",
       "      <td>44</td>\n",
       "      <td>54640</td>\n",
       "      <td></td>\n",
       "      <td>8.736</td>\n",
       "      <td>0.259</td>\n",
       "      <td>7</td>\n",
       "      <td>...</td>\n",
       "      <td>6740</td>\n",
       "      <td>754</td>\n",
       "      <td>3242</td>\n",
       "      <td>18520</td>\n",
       "      <td>3.07</td>\n",
       "      <td>31819</td>\n",
       "      <td>1772</td>\n",
       "      <td>13331</td>\n",
       "      <td>16716</td>\n",
       "      <td>{'x': -71.3759815680945, 'y': 41.8755001649055...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>3554</td>\n",
       "      <td>3554</td>\n",
       "      <td>Fall River</td>\n",
       "      <td>City</td>\n",
       "      <td>MA</td>\n",
       "      <td>25</td>\n",
       "      <td>23000</td>\n",
       "      <td></td>\n",
       "      <td>31.022</td>\n",
       "      <td>7.202</td>\n",
       "      <td>7</td>\n",
       "      <td>...</td>\n",
       "      <td>9011</td>\n",
       "      <td>759</td>\n",
       "      <td>4247</td>\n",
       "      <td>23558</td>\n",
       "      <td>3.00</td>\n",
       "      <td>41857</td>\n",
       "      <td>3098</td>\n",
       "      <td>13521</td>\n",
       "      <td>25238</td>\n",
       "      <td>{'x': -71.1469910908576, 'y': 41.6981001567767...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>3555</td>\n",
       "      <td>3555</td>\n",
       "      <td>Somerset</td>\n",
       "      <td>Census Designated Place</td>\n",
       "      <td>MA</td>\n",
       "      <td>25</td>\n",
       "      <td>62465</td>\n",
       "      <td></td>\n",
       "      <td>8.109</td>\n",
       "      <td>3.867</td>\n",
       "      <td>6</td>\n",
       "      <td>...</td>\n",
       "      <td>2771</td>\n",
       "      <td>91</td>\n",
       "      <td>287</td>\n",
       "      <td>5260</td>\n",
       "      <td>2.98</td>\n",
       "      <td>7143</td>\n",
       "      <td>156</td>\n",
       "      <td>5723</td>\n",
       "      <td>1264</td>\n",
       "      <td>{'x': -71.15319106847441, 'y': 41.748500174901...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>3556</td>\n",
       "      <td>3556</td>\n",
       "      <td>New Bedford</td>\n",
       "      <td>City</td>\n",
       "      <td>MA</td>\n",
       "      <td>25</td>\n",
       "      <td>45000</td>\n",
       "      <td></td>\n",
       "      <td>20.122</td>\n",
       "      <td>3.904</td>\n",
       "      <td>7</td>\n",
       "      <td>...</td>\n",
       "      <td>8813</td>\n",
       "      <td>910</td>\n",
       "      <td>4701</td>\n",
       "      <td>24083</td>\n",
       "      <td>3.01</td>\n",
       "      <td>41511</td>\n",
       "      <td>3333</td>\n",
       "      <td>16711</td>\n",
       "      <td>21467</td>\n",
       "      <td>{'x': -70.93370908847608, 'y': 41.651800155406...</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 48 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "       FID             NAME                    CLASS  ST STFIPS PLACEFIP  \\\n",
       "3552  3552  East Providence                     City  RI     44    22960   \n",
       "3553  3553        Pawtucket                     City  RI     44    54640   \n",
       "3554  3554       Fall River                     City  MA     25    23000   \n",
       "3555  3555         Somerset  Census Designated Place  MA     25    62465   \n",
       "3556  3556      New Bedford                     City  MA     25    45000   \n",
       "\n",
       "     CAPITAL  AREALAND  AREAWATER  POP_CLASS  ...  MARHH_NO_C  MHH_CHILD  \\\n",
       "3552            13.405      3.208          6  ...        5658        306   \n",
       "3553             8.736      0.259          7  ...        6740        754   \n",
       "3554            31.022      7.202          7  ...        9011        759   \n",
       "3555             8.109      3.867          6  ...        2771         91   \n",
       "3556            20.122      3.904          7  ...        8813        910   \n",
       "\n",
       "      FHH_CHILD  FAMILIES  AVE_FAM_SZ  HSE_UNITS  VACANT  OWNER_OCC  \\\n",
       "3552       1414     12850        2.99      21309     779      12096   \n",
       "3553       3242     18520        3.07      31819    1772      13331   \n",
       "3554       4247     23558        3.00      41857    3098      13521   \n",
       "3555        287      5260        2.98       7143     156       5723   \n",
       "3556       4701     24083        3.01      41511    3333      16711   \n",
       "\n",
       "      RENTER_OCC                                              SHAPE  \n",
       "3552        8434  {'x': -71.3608270663031, 'y': 41.8015001782688...  \n",
       "3553       16716  {'x': -71.3759815680945, 'y': 41.8755001649055...  \n",
       "3554       25238  {'x': -71.1469910908576, 'y': 41.6981001567767...  \n",
       "3555        1264  {'x': -71.15319106847441, 'y': 41.748500174901...  \n",
       "3556       21467  {'x': -70.93370908847608, 'y': 41.651800155406...  \n",
       "\n",
       "[5 rows x 48 columns]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sdf = pd.DataFrame.spatial.from_featureclass(\n",
    "    \"path\\to\\your\\data\\census_example\\cities.shp\")\n",
    "\n",
    "\n",
    "sdf.tail()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example: Reading a Featureclass from FileGDB\n",
    "\n",
    "> You must have `fiona` installed if you use the `from_featureclass()` method to read a feature class from FileGDB with a Python interpreter that does not have access to `ArcPy`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>OBJECTID</th>\n",
       "      <th>FID</th>\n",
       "      <th>NAME</th>\n",
       "      <th>CLASS</th>\n",
       "      <th>ST</th>\n",
       "      <th>STFIPS</th>\n",
       "      <th>PLACEFIP</th>\n",
       "      <th>CAPITAL</th>\n",
       "      <th>AREALAND</th>\n",
       "      <th>AREAWATER</th>\n",
       "      <th>...</th>\n",
       "      <th>MARHH_NO_C</th>\n",
       "      <th>MHH_CHILD</th>\n",
       "      <th>FHH_CHILD</th>\n",
       "      <th>FAMILIES</th>\n",
       "      <th>AVE_FAM_SZ</th>\n",
       "      <th>HSE_UNITS</th>\n",
       "      <th>VACANT</th>\n",
       "      <th>OWNER_OCC</th>\n",
       "      <th>RENTER_OCC</th>\n",
       "      <th>SHAPE</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <td>0</td>\n",
       "      <td>1</td>\n",
       "      <td>0</td>\n",
       "      <td>College</td>\n",
       "      <td>Census Designated Place</td>\n",
       "      <td>AK</td>\n",
       "      <td>02</td>\n",
       "      <td>16750</td>\n",
       "      <td></td>\n",
       "      <td>18.670</td>\n",
       "      <td>0.407</td>\n",
       "      <td>...</td>\n",
       "      <td>936</td>\n",
       "      <td>152</td>\n",
       "      <td>339</td>\n",
       "      <td>2640</td>\n",
       "      <td>3.13</td>\n",
       "      <td>4501</td>\n",
       "      <td>397</td>\n",
       "      <td>2395</td>\n",
       "      <td>1709</td>\n",
       "      <td>{'x': -147.82719115699996, 'y': 64.84830019400...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>1</td>\n",
       "      <td>2</td>\n",
       "      <td>1</td>\n",
       "      <td>Fairbanks</td>\n",
       "      <td>City</td>\n",
       "      <td>AK</td>\n",
       "      <td>02</td>\n",
       "      <td>24230</td>\n",
       "      <td></td>\n",
       "      <td>31.857</td>\n",
       "      <td>0.815</td>\n",
       "      <td>...</td>\n",
       "      <td>2259</td>\n",
       "      <td>395</td>\n",
       "      <td>1058</td>\n",
       "      <td>7187</td>\n",
       "      <td>3.15</td>\n",
       "      <td>12357</td>\n",
       "      <td>1282</td>\n",
       "      <td>3863</td>\n",
       "      <td>7212</td>\n",
       "      <td>{'x': -147.72638162999996, 'y': 64.83809069700...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>2</td>\n",
       "      <td>3</td>\n",
       "      <td>2</td>\n",
       "      <td>Kalispell</td>\n",
       "      <td>City</td>\n",
       "      <td>MT</td>\n",
       "      <td>30</td>\n",
       "      <td>40075</td>\n",
       "      <td></td>\n",
       "      <td>5.458</td>\n",
       "      <td>0.004</td>\n",
       "      <td>...</td>\n",
       "      <td>1433</td>\n",
       "      <td>147</td>\n",
       "      <td>480</td>\n",
       "      <td>3494</td>\n",
       "      <td>2.92</td>\n",
       "      <td>6532</td>\n",
       "      <td>390</td>\n",
       "      <td>3458</td>\n",
       "      <td>2684</td>\n",
       "      <td>{'x': -114.31606412399998, 'y': 48.19780017900...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>3</td>\n",
       "      <td>4</td>\n",
       "      <td>3</td>\n",
       "      <td>Post Falls</td>\n",
       "      <td>City</td>\n",
       "      <td>ID</td>\n",
       "      <td>16</td>\n",
       "      <td>64810</td>\n",
       "      <td></td>\n",
       "      <td>9.656</td>\n",
       "      <td>0.045</td>\n",
       "      <td>...</td>\n",
       "      <td>1851</td>\n",
       "      <td>205</td>\n",
       "      <td>467</td>\n",
       "      <td>4670</td>\n",
       "      <td>3.13</td>\n",
       "      <td>6697</td>\n",
       "      <td>328</td>\n",
       "      <td>4611</td>\n",
       "      <td>1758</td>\n",
       "      <td>{'x': -116.93792709799999, 'y': 47.71555468000...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>4</td>\n",
       "      <td>5</td>\n",
       "      <td>4</td>\n",
       "      <td>Dishman</td>\n",
       "      <td>Census Designated Place</td>\n",
       "      <td>WA</td>\n",
       "      <td>53</td>\n",
       "      <td>17985</td>\n",
       "      <td></td>\n",
       "      <td>3.378</td>\n",
       "      <td>0.000</td>\n",
       "      <td>...</td>\n",
       "      <td>1096</td>\n",
       "      <td>131</td>\n",
       "      <td>345</td>\n",
       "      <td>2564</td>\n",
       "      <td>2.96</td>\n",
       "      <td>4408</td>\n",
       "      <td>257</td>\n",
       "      <td>2635</td>\n",
       "      <td>1516</td>\n",
       "      <td>{'x': -117.27780913799995, 'y': 47.65654568400...</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>5 rows × 49 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "   OBJECTID  FID        NAME                    CLASS  ST STFIPS PLACEFIP  \\\n",
       "0         1    0     College  Census Designated Place  AK     02    16750   \n",
       "1         2    1   Fairbanks                     City  AK     02    24230   \n",
       "2         3    2   Kalispell                     City  MT     30    40075   \n",
       "3         4    3  Post Falls                     City  ID     16    64810   \n",
       "4         5    4     Dishman  Census Designated Place  WA     53    17985   \n",
       "\n",
       "  CAPITAL  AREALAND  AREAWATER  ...  MARHH_NO_C  MHH_CHILD  FHH_CHILD  \\\n",
       "0            18.670      0.407  ...         936        152        339   \n",
       "1            31.857      0.815  ...        2259        395       1058   \n",
       "2             5.458      0.004  ...        1433        147        480   \n",
       "3             9.656      0.045  ...        1851        205        467   \n",
       "4             3.378      0.000  ...        1096        131        345   \n",
       "\n",
       "   FAMILIES  AVE_FAM_SZ  HSE_UNITS  VACANT  OWNER_OCC  RENTER_OCC  \\\n",
       "0      2640        3.13       4501     397       2395        1709   \n",
       "1      7187        3.15      12357    1282       3863        7212   \n",
       "2      3494        2.92       6532     390       3458        2684   \n",
       "3      4670        3.13       6697     328       4611        1758   \n",
       "4      2564        2.96       4408     257       2635        1516   \n",
       "\n",
       "                                               SHAPE  \n",
       "0  {'x': -147.82719115699996, 'y': 64.84830019400...  \n",
       "1  {'x': -147.72638162999996, 'y': 64.83809069700...  \n",
       "2  {'x': -114.31606412399998, 'y': 48.19780017900...  \n",
       "3  {'x': -116.93792709799999, 'y': 47.71555468000...  \n",
       "4  {'x': -117.27780913799995, 'y': 47.65654568400...  \n",
       "\n",
       "[5 rows x 49 columns]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sdf = pd.DataFrame.spatial.from_featureclass(\n",
    "    \"path\\to\\your\\data\\census_example\\census.gdb\\cities\")\n",
    "\n",
    "\n",
    "sdf.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Saving Spatially Enabled DataFrames\n",
    "\n",
    "The SEDF can export data to various data formats for use in other applications.\n",
    "\n",
    "### Export Options\n",
    "\n",
    "- [Feature Layers](https://doc.arcgis.com/en/arcgis-online/share-maps/hosted-web-layers.htm)\n",
    "- [Feature Collections](/python/api-reference/arcgis.features.toc.html#featurelayercollection)\n",
    "- [Feature Set](/python/api-reference/arcgis.features.toc.html#featureset)\n",
    "- [GeoJSON](http://geojson.org/)\n",
    "- [Feature Class](https://pro.arcgis.com/en/pro-app/latest/help/data/feature-classes/feature-classes.htm)\n",
    "- [Pickle](https://pythontips.com/2013/08/02/what-is-pickle-in-python/)\n",
    "- [HDF](https://support.hdfgroup.org/HDF5/Tutor/HDF5Intro.pdf)\n",
    "\n",
    "### Export to Feature Class\n",
    "\n",
    "The SEDF allows for the export of whole datasets or partial datasets.\n",
    "\n",
    "#### Example: Export a whole dataset to a shapefile:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'c:\\\\output_examples\\\\census.shp'"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sdf.spatial.to_featureclass(location=r\"c:\\output_examples\\census.shp\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> The ArcGIS API for Python installs on all `macOS` and `Linux` machines, as well as those `Windows` machines not using Python interpreters that have access to `ArcPy` will only be able to write out to shapefile format with the `to_featureclass` method. Writing to file geodatabases requires the `ArcPy` site-package.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Example: Export dataset with a subset of columns and top 5 records to a shapefile:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "PLACENS                       GEOID                         NAMELSAD                      CLASSFP\n",
      "FUNCSTAT                      ALAND                         AWATER                        INTPTLAT\n"
     ]
    }
   ],
   "source": [
    "for a, b, c, d in zip(sdf.columns[::4], sdf.columns[1::4], sdf.columns[2::4], sdf.columns[3::4]):\n",
    "    print(\"{:<30}{:<30}{:<30}{:<}\".format(a, b, c, d))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'/path/to/your/data/directory/sdf_head_output.shp'"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "columns = ['NAME', 'ST', 'CAPITAL', 'STFIPS', 'POP2000', 'POP2007', 'SHAPE']\n",
    "sdf[columns].head().spatial.to_featureclass(\n",
    "    location=r\"/path/to/your/data/directory/sdf_head_output.shp\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Example: Export dataset to a featureclass in FileGDB:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdf.spatial.to_featureclass(location=r\"c:\\output_examples\\census.gdb\\cities\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Publish as a Feature Layer\n",
    "\n",
    "The SEDF allows for the publishing of datasets as feature layers.\n",
    "\n",
    "#### Example: Publishing as a feature layer:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n",
       "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n",
       "                       <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=95455c26d51d4fcaaf4cb88cfe7d5293' target='_blank'>\n",
       "                        <img src='http://static.arcgis.com/images/desktopapp.png' class=\"itemThumbnail\">\n",
       "                       </a>\n",
       "                    </div>\n",
       "\n",
       "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n",
       "                        <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=95455c26d51d4fcaaf4cb88cfe7d5293' target='_blank'><b>census_cities</b>\n",
       "                        </a>\n",
       "                        <br/><img src='https://geosaurus.maps.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/featureshosted16.png' style=\"vertical-align:middle;\">Feature Layer Collection by api_data_owner\n",
       "                        <br/>Last Modified: September 11, 2019\n",
       "                        <br/>0 comments, 0 views\n",
       "                    </div>\n",
       "                </div>\n",
       "                "
      ],
      "text/plain": [
       "<Item title:\"census_cities\" type:Feature Layer Collection owner:api_data_owner>"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "lyr = sdf.spatial.to_featurelayer('census_cities', folder='census')\n",
    "lyr"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.2"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": true,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
